docs(creative): clarify cta errors, carousel defaults, asset_types and product formats - #8949

Closes #8628
Closes #8629
Closes #8630
Closes #8631

Problem

An implementer building sync_creatives validation against v3.2.7 found four places where the creative schemas and docs read two ways. The maintainer answered each issue with the intended rule. This PR writes those answers into the schemas and docs. It builds on #8937 (card_image_sizes), #8940 and #8941 (format conformance), which merged just before.

Please confirm: schema defaults vs. #8941's omitted-parameter rule

#8941 says an omitted narrowing parameter sets no limit. Under #8629 a silent allowed_card_media_asset_types means ['image'] ("the parameter states its own default"), so the two texts disagreed. This PR adds one exception wherever #8941's rule is stated:

• docs/creative/task-reference/sync_creatives.mdx
• docs/creative/canonical-formats.mdx
• docs/creative/formats.mdx

The exception: a parameter whose canonical schema states a default applies that default when omitted. The rule as written also contradicted defaults that already exist, such as every canonical's default slots and seller_rendered_stateful_display.clickthrough: "required". Among the canonical defaults, only allowed_card_media_asset_types changes what a seller may refuse. If you prefer, this can be narrowed to "a parameter that states its own default".

Changes

#8628 cta_values and CREATIVE_VALUE_NOT_ALLOWED

• enums/error-code.json: the code covers a value outside the closed set the targeted option declares (cta_values on canonical formats, allowed_values in text-asset requirements). It turns on the declared set, not the container, so a card's per-card cta is covered.
• The declared set goes in error.details.accepted_values, the canonical key in core/error.json; also sending allowed_values is harmless. The enumMetadata suggestion names accepted_values.
• error.field examples are now creatives[0].assets.cta.content and creatives[0].assets.cards[2].cta. This drops the creative_manifest segment from the maintainer's example (creatives[0].creative_manifest.assets.cards[2].cta):
  • sync_creatives items (core/creative-asset.json) carry assets directly, and core/error.json defines field as a request-payload path.
  • The segment came from the old assets[0].value example.
  • The training agent already emits creatives[0].assets.cta.content.
• core/requirements/text-asset-requirements.json (allowed_values): MUST reject and set error.field; SHOULD carry the list in error.details.accepted_values. This matches the enum, so a seller that sends the old allowed_values stays conformant. core/assets/card-asset.json (cta) names the same code.
• sync_creatives.mdx: the format-conformance paragraph and the error table use accepted_values and mention the per-card cta.
• canonical-formats.mdx Reels table: the buyer ships assets.cta.content, not assets.cta.text.
• Regenerated docs/snippets/compliance-error-codes.mdx.
• Training agent: CREATIVE_VALUE_NOT_ALLOWED details carry accepted_values instead of allowed_values. No storyboard reads the details key.

#8629 image_carousel card media and card count

• allowed_card_media_asset_types gains "default": ["image"]. A declaration that omits both it and the deprecated allowed_card_asset_types alias accepts image cards only; declare ['image', 'video'] for mixed-media carousels.
• The format description keeps the narrowing framing: media can carry image or video, and the parameter narrows that set and defaults to ['image'].
• min_cards / max_cards only narrow the cards slot. max_cards: 35 alone still caps at 10; a product that takes 35 cards restates the slot with max: 35 and may also set max_cards: 35.
• responsive_creative: pool counts narrow their slot the same way. card-asset.json media: image only when the parameter is omitted.
• carousels.mdx gains a "Card media and card count" section with a 35-card example. canonical-formats.mdx (params.slots section, Pinterest Idea Pin row) says the same.
• The schema-default exception above, in three files.

#8630 list_creative_formats asset_types

• media-buy/ and creative/list-creative-formats-request.json: keep formats that declare every one of the requested types. An asset counts whether it is required or optional, and whether it is at the top level or inside a repeatable_group. The example matches.
• migration/creatives.mdx states the all-of rule and that any-of means one call per type, unioned. list_creatives.mdx ends its matching paragraph with a contrast to its own any-of filter over creatives, which is unchanged.
• Reference creative agent: list_creative_formats applies all-of (it applied any-of), and its tool description says so. No storyboard sends list_creative_formats with asset_types.

#8631 multi-publisher products without placements[]

• core/product.json format_options: adopts the suggested wording. Such a product MUST NOT carry publisher-scoped declarations; when no product-local declaration remains, the seller MUST publish placements[] or split the product by publisher.
• formats.mdx, canonical-formats.mdx and media-products.mdx state:
  • the rule;
  • that the intersection is taken by declaration identity;
  • that an empty intersection is unsellable as published.
• The per-slice rule now describes how a buyer grades a product that breaks the rule. The "product-level list is the union" sentences now apply to products that publish placements[].

Tests

• Schema validation 36/36, example validation 79/79, canonical conventions, fixtures (27) and negative fixtures (88/88), x-added-in-3-3-sweep 6/6.
• mcp-schema-projection 36/36 after rebasing on main (2dc672e): the controller request measures 1_385_258 bytes, under main's 1_387_000 bound, so this PR leaves the bound alone.
• training-agent-native-in-feed-options.test.ts + creative-agent.test.ts: 139/139.
  • The two updated training-agent assertions fail with allowed_values.
  • The new all-of test fails with the old any-of filter.
• Server typecheck passes.
• These also pass:
  • compliance snippet and symbol-link tests (28/28) and build:compliance --check;
  • lint-error-codes and sdk-response-conformance (14/14);
  • owned links, docs nav, schema links, and the docs JSON field audit.
• json-schema-validation --file passes on the changed docs.
• snippet-validation --file passes except for the 10 existing Python/JS snippets in sync_creatives.mdx, which fail locally only because the SDKs are not installed here. No code snippets were added.

Changeset

.changeset/creative-wording-errata-cta-carousel-filters.md, minor.

• The maintainer called cta_values and CREATIVE_VALUE_NOT_ALLOWED: details key, closed-set name, per-card cta, and assets.cta.text #8628, image_carousel: default of allowed_card_media_asset_types, and whether max_cards can exceed the cards slot's default max #8629 and product.json and formats.mdx: make the multi-publisher, no-placements format_options rule explicit #8631 description fixes and patch-eligible, and put list-creative-formats-request: say whether asset_types matches any or all of the requested types, and whether repeatable-group assets count #8630 in "the next creative errata pass".
• list-creative-formats-request: say whether asset_types matches any or all of the requested types, and whether repeatable-group assets count #8630 changes the result an any-of seller returned before (the reference creative agent was one, and migration/creatives.mdx documented OR), so the changeset is minor, like docs(creative): sellers accept creatives that conform to the declared format option #8941. In 3.3 beta pre-mode the version outcome is the same; it only keeps the change out of a 3.2.x patch backport.
• The branch edits 3.3-only text from feat(schema): add card_image_sizes to image_carousel #8937 and docs(creative): sellers accept creatives that conform to the declared format option #8941, so it does not cherry-pick to 3.2.x as is.

Out of scope / follow-ups

• image_carousel declaring cta_values: the maintainer agreed in cta_values and CREATIVE_VALUE_NOT_ALLOWED: details key, closed-set name, per-card cta, and assets.cta.text #8628 and said it would be tracked as a separate schema change. No tracking issue exists yet; one should be opened before this PR closes cta_values and CREATIVE_VALUE_NOT_ALLOWED: details key, closed-set name, per-card cta, and assets.cta.text #8628.
• docs/creative/implementing-creative-agents.mdx uses cards_min / cards_max, which are not image_carousel parameters.

🤖 Generated with Claude Code